Skip to content

Add OpenAPI contract - phase 1 scope#535

Merged
marcvergees merged 3 commits into
fireform-core:developmentfrom
chetanr25:openapi_contracts
Jun 16, 2026
Merged

Add OpenAPI contract - phase 1 scope#535
marcvergees merged 3 commits into
fireform-core:developmentfrom
chetanr25:openapi_contracts

Conversation

@chetanr25

Copy link
Copy Markdown
Collaborator

Add OpenAPI contract - phase 1 scope

Closes #511 (well, the part about having the contract in the codebase).

Based on the feedback from the discussion, the contract has been scoped down to what we're actually building in phase 1. Agencies and auth are out for now the assumption is that FireForm runs inside an org's local network, so there's no real need for auth at this stage.

What changed from the originally proposed contract:

  • Agencies and auth are out scoped to phase 2 as agreed in Proposal to design and follow OpenAPI contract #511
  • Health is now a single endpoint instead of two the Ollama model/load detail is folded into /api/v1/health directly
  • Cleaned up a few places where agency_id was marked required, which would've broken things once the agencies registry was removed

Contract structure:

contracts/
├── openapi.yaml
├── path/
│   ├── input.yaml
│   ├── extraction.yaml
│   ├── forms.yaml
│   ├── incidents.yaml
│   ├── reporting.yaml
│   ├── templates.yaml
│   ├── jobs.yaml
│   └── system.yaml
└── schemas/
    ├── canonical-incident.yaml
    ├── common.yaml
    ├── enums.yaml
    ├── extraction-record.yaml
    ├── form-record.yaml
    ├── incident-record.yaml
    ├── input-record.yaml
    ├── reporting.yaml
    ├── system.yaml
    └── template.yaml

The contract is split into path definitions and schemas to keep it readable as it grows. openapi.yaml is the root entry point.

Fixes: #534

@chetanr25 chetanr25 marked this pull request as ready for review June 9, 2026 06:10
@chetanr25 chetanr25 closed this Jun 12, 2026
@chetanr25 chetanr25 deleted the openapi_contracts branch June 12, 2026 15:00
@chetanr25 chetanr25 restored the openapi_contracts branch June 12, 2026 15:00
@chetanr25 chetanr25 reopened this Jun 12, 2026
# PATCH /api/v1/extract/{extract_id}
# POST /api/v1/extract/{extract_id}/validate

extract_by_input:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good

detail:
ollama_status: "connection_refused"

extract_by_id:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same

issue: "Must be one of: confirmed, probable, suspected, undetermined"
value: "maybe"

validate:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good approach.

Comment thread contracts/path/jobs.yaml
# Layer 8 Async Job Status (Cross-cutting)
# GET /api/v1/jobs/{job_id}

job_by_id:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, that way we'll be able to manage async jobs.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's gonna be so useful when creating the analytics dashboard. Probably, soon we'll have to add more contracts now. I cannot think of more rn, since we haven't debated it yet.

@marcvergees marcvergees merged commit c87ab2e into fireform-core:development Jun 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants